<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<!--
Generated from $Fink: x11.en.xml,v 1.22 2007/08/15 21:57:04 dmacks Exp $
-->
<title>Fink Documentation - Running X11 on Darwin and Mac OS X</title></head><body>
<table width="100%" cellspacing="0">
<tr valign="bottom">
<td align="center">
Available Languages:  | 
English | 
<a href="x11.es.html">Espa&ntilde;ol</a> | 
<a href="x11.fr.html">Fran&ccedil;ais</a> | 
<a href="x11.ja.html">&#26085;&#26412;&#35486; (Nihongo)</a> | 
<a href="x11.pt.html">Portugu&ecirc;s</a> | 
<a href="x11.ru.html">&#1056;&#1091;&#1089;&#1089;&#1082;&#1080;&#1081; (Russkiy)</a> | 
<a href="x11.zh.html">&#20013;&#25991; (&#31616;) (Simplified Chinese)</a> | 
</td>
</tr>
</table>
<h1 style="text-align: center;">Running X11 on Darwin and Mac OS X</h1>
    <p>
This document is about running X11 / XFree86 / Xtools on Apple's Mac
OS X and Darwin systems.
It gives an introduction and a history of development, then goes on to
describe the current situation and the many options you have to use
X11 with or without Fink.
</p>
  <h2>Contents</h2><ul><li><a href="#intro"><b>1 Introduction</b></a><ul><li><a href="#intro.def-x11">1.1 What is X11?</a></li><li><a href="#intro.def-macosx">1.2 What is Mac OS X?</a></li><li><a href="#intro.def-darwin">1.3 What is Darwin?</a></li><li><a href="#intro.def-xfree86">1.4 What is XFree86?</a></li><li><a href="#intro.def-xtools">1.5 What is Xtools?</a></li><li><a href="#intro.client-server">1.6 Client and Server</a></li><li><a href="#intro.rootless">1.7 What does rootless mean?</a></li><li><a href="#intro.wm">1.8 What is a window manager?</a></li><li><a href="#intro.desktop">1.9 What are Quartz/Aqua, Gnome, and KDE?</a></li></ul></li><li><a href="#history"><b>2 History</b></a><ul><li><a href="#history.early">2.1 The early days</a></li><li><a href="#history.xonx-forms">2.2 XonX forms</a></li><li><a href="#history.root-or-not">2.3 To root or not to root</a></li></ul></li><li><a href="#inst-xfree86"><b>3 Getting and Installing X11</b></a><ul><li><a href="#inst-xfree86.fink">3.1 Installing X11 via Fink</a></li><li><a href="#inst-xfree86.apple-binary">3.2 Apple's Binaries</a></li><li><a href="#inst-xfree86.official-binary">3.3 The Official Binaries</a></li><li><a href="#inst-xfree86.official-source">3.4 The Official Source</a></li><li><a href="#inst-xfree86.latest-cvs">3.5 The Latest Development Source</a></li><li><a href="#inst-xfree86.switching-x11">3.6 Replacing X11</a></li><li><a href="#inst-xfree86.fink-summary">3.7 Fink package summary</a></li></ul></li><li><a href="#run-xfree86"><b>4 Starting X11</b></a><ul><li><a href="#run-xfree86.darwin">4.1 Darwin</a></li><li><a href="#run-xfree86.macosx-41">4.2 Mac OS X + XFree86 4.x.y</a></li><li><a href="#run-xfree86.starting-xorg">4.3 Starting X.org</a></li><li><a href="#run-xfree86.starting-apples-x11">4.4 Starting Apple's X11</a></li><li><a href="#run-xfree86.applex11tools">4.5 The applex11tools package</a></li><li><a href="#run-xfree86.xinitrc">4.6 The .xinitrc File</a></li><li><a href="#run-xfree86.oroborosx">4.7 OroborOSX</a></li></ul></li><li><a href="#xtools"><b>5 Xtools</b></a><ul><li><a href="#xtools.install">5.1 Installing Xtools</a></li><li><a href="#xtools.run">5.2 Running Xtools</a></li><li><a href="#xtools.opengl">5.3 OpenGL Notes</a></li></ul></li><li><a href="#other"><b>6 Other X11 Possibilities</b></a><ul><li><a href="#other.vnc">6.1 VNC</a></li><li><a href="#other.wiredx">6.2 WiredX</a></li><li><a href="#other.exodus">6.3 eXodus</a></li></ul></li><li><a href="#trouble"><b>7 Troubleshooting XFree86</b></a><ul><li><a href="#trouble.immedate-quit">7.1 When I launch XDarwin, it quits
or crashes almost immediately</a></li><li><a href="#trouble.black">7.2 Black icons in the GNOME panel or in the
menu of a GNOME application</a></li><li><a href="#trouble.keyboard">7.3 The keyboard doesn't work in XFree86</a></li><li><a href="#trouble.delete-key">7.4 The Backspace key doesn't work</a></li><li><a href="#trouble.locale">7.5 "Warning: locale not supported by C library"</a></li></ul></li><li><a href="#tips"><b>8 Usage Tips</b></a><ul><li><a href="#tips.terminal-app">8.1 Launching X11 apps from Terminal.app</a></li><li><a href="#tips.open">8.2 Launching Aqua apps from an xterm</a></li><li><a href="#tips.copy-n-paste">8.3 Copy and Paste</a></li></ul></li></ul><h2><a name="intro">1 Introduction</a></h2>
    
    
    <h3><a name="intro.def-x11">1.1 What is X11?</a></h3>
      
      <p>
The <a href="http://www.x.org/">X Window System</a> Version 11,
or X11 for short, is a graphics display system with a
network-transparent client-server architecture.
It allows applications to draw pixels, lines, text, images, etc. on
your screen.
X11 also comes with additional libraries that let applications easily
draw user interfaces, i.e. buttons, text fields, and so on.
</p>
      <p>
X11 is the de facto standard graphics system in the Unix world.
It comes with Linux, the *BSDs and most commercial Unix flavors.
Desktop environments like CDE, KDE and GNOME run on top of it.
</p>
    
    <h3><a name="intro.def-macosx">1.2 What is Mac OS X?</a></h3>
      
      <p>
        <a href="http://www.apple.com/macosx/">Mac OS X</a> is an
operating system produced by <a href="http://www.apple.com/">Apple</a>.
Like its predecessors NeXTStep and OpenStep, it is based on BSD and is
thus a member of the Unix OS family.
However, it comes with a proprietary graphics display system.
The graphics engine is called Quartz and the look and feel is called
Aqua, although the two names are often used intercheangably.
</p>
    
    <h3><a name="intro.def-darwin">1.3 What is Darwin?</a></h3>
      
      <p>
        <a href="http://opendarwin.org/">Darwin</a> is
basically a stripped-down version of Mac OS X that is available free
of charge and with full source code.
It does not contain Quartz, Aqua, or any other related technology.
By default, it only offers a text console.
</p>
    
    <h3><a name="intro.def-xfree86">1.4 What is XFree86?</a></h3>
      
      <p>
        <a href="http://www.xfree86.org/">XFree86</a> is an open source
implementation of X11.
It was initially developed to run on Intel x86 PCs, hence the name.
Nowadays, it runs on many architectures and operating systems,
including OS/2, Darwin, Mac OS X and Windows.
</p>
    
    <h3><a name="intro.def-xtools">1.5 What is Xtools?</a></h3>
      
      <p>
Xtools is a product of <a href="http://www.tenon.com/">Tenon
Intersystems</a>.
It is a version of X11 for Mac OS X, based on XFree86.  
</p>
<p>Note:  Development apparently stopped sometime before OS 10.3 was released.</p>
    
    <h3><a name="intro.client-server">1.6 Client and Server</a></h3>
      
      <p>
X11 has a client-server architecture.
There is one central program that does the actual drawing and
coordinates access by several applications; that is the server.
An application that wants to draw using X11 connects to the server and
tells it what to draw.
Thus applications are called clients in the X11 world.
</p>
      <p>
X11 allows the server and the clients to be on different machines,
which often results in confusion over the terms.
In an environment with workstations and servers, you will run the X11
display server on the workstation machine and the applications (the X
clients) on the server machine.
So when talking about the "server", that means the X11 display server
program, not the machine hidden in your wardrobe.
</p>
    
    <h3><a name="intro.rootless">1.7 What does rootless mean?</a></h3>
      
      <p>
A little background:
X11 models the screen as a hierarchy of windows contained in each
other.
At the top of the hierarchy is a special window which is the size of
the screen and contains all other windows.
This window contains the desktop background and is called the "root
window".
</p>
      <p>
Now back on topic:
Like any graphical environment, X11 was written to stand alone and
have full control over the screen.
In Mac OS X, Quartz already governs the screen, so one must make
arrangements if both are to get along together.
</p>
      <p>
One arrangement is to let the two take turns.
Each environment gets a complete screen, but only one of them is
visible at a time and the user can switch between them.
This is called full-screen or rooted mode.
It is called rooted because there is a perfectly normal root window on
the X11 screen that works like on other systems.
</p>
      <p>
Another arrangement is to mix the two environments window by window.
This eliminates the need to switch between two screens.
It also eliminates the X11 root window, because Quartz already takes
care of the desktop background.
Because there is no (visible) root window, this mode is called
"rootless".  It is the most comfortable way to use X11 on Mac OS X.
</p>
    
    <h3><a name="intro.wm">1.8 What is a window manager?</a></h3>
      
      <p>
In most graphical environments the look of window frames (title bar,
close button, etc.) is defined by the system.
X11 is different.
With X11, the window frames (also called "decoration") are provided by
a separate program, called the window manager.
In most respects, the window manager is just another client
application; it is started the same way and talks to the X server
through the same channels.
</p>
      <p>
There is a large number of different window managers to choose from.
<a href="http://www.xwinman.org/">xwinman.org</a> has a
comprehensive list.
Most popular ones allow the user to customize the appearance via
so-called <a href="http://www.themes.org/">themes</a>.
Many window managers also provide additional functionality, like pop
up menus in the root window, docks or launch buttons.
</p>
      <p>
Many window managers have been packaged for Fink; here is a
<a href="http://pdb.finkproject.org/pdb/section.php/x11-wm">    
current list.
</a>
      </p>
    
    <h3><a name="intro.desktop">1.9 What are Quartz/Aqua, Gnome, and KDE?</a></h3>
      
      <p>
They are desktop environments, and there are many others.  Their purpose 
is to provide additional framework to applications, so that their look, 
feel, and behaviour can be visually consistent.  Example: 
</p>
      <p> graphics engine : X11
</p>
      <p> window manager:
<a href="http://sawmill.sourceforge.net/">sawfish</a>
      </p>
      <p> desktop: <a href="http://www.gnome.org/">Gnome</a>
      </p>
      <p>
The lines between graphics display engine, window manager,
and desktop are blurred because similar, or the same functionality, 
may be implemented by one or more of them. This is one reason why a
particular window manager may not be able to be used with a
particular desktop environment.

</p>
      <p>
Many applications are developed to integrate with a particular desktop.  
Most often by installing the libraries for the desktop environment 
(and the other underlying libraries) that an application was developed 
for, the application will work with limited or no function loss.  
Examples are the increasing 
<a href="http://pdb.finkproject.org/pdb/section.php/gnome">
selection of GNOME applications 
</a>
available to be installed and run without running GNOME.  
Unfortunately, the same 
<a href="http://www.finkproject.org/faq/usage-fink.php#kde">
progress is not quite yet able to be made
</a>
with <a href="http://www.kde.org/">KDE applications.</a>
      </p>
    
  <h2><a name="history">2 History</a></h2>
    
    
    
      <p>[Sorry for the epic language, I couldn't resist...]</p>
    
    <h3><a name="history.early">2.1 The early days</a></h3>
      
      <p>
In the beginning, there was void.
Darwin was in its infancy, Mac OS X was still in development and there
was no X11 implementation for both of them.
</p>
      <p>
Then there came John Carmack and ported XFree86 to Mac OS X Server,
which was the only OS in the Darwin family available at that time.
Later that port was updated for XFree86 4.0 and Darwin 1.0 by Dave
Zarzycki.
The patches found their way into the Darwin CVS repository and slept
there, waiting for things to come.
</p>
    
    <h3><a name="history.xonx-forms">2.2 XonX forms</a></h3>
      
      <p>
One fine day Torrey T. Lyons came along and gave the Darwin patches
the attention they had been waiting for.
Finally, he brought them to a new home, the official XFree86 CVS
repository.
This was the time of the Mac OS X Public Beta and Darwin 1.2.
XFree86 4.0.2 worked fine on Darwin, but on Mac OS X it required users
to log out of Aqua and go to the console to run it.
So Torrey gathered the <a href="http://mrcla.com/XonX/">XonX team</a> around
him and set out on a voyage to bring XFree86 to Mac OS X.
</p>
      <p>
At about the same time Tenon started to build Xtools, using XFree86
4.0 as the foundation.
</p>
    
    <h3><a name="history.root-or-not">2.3 To root or not to root</a></h3>
      
      <p>
Soon the XonX team had XFree86 running in a fullscreen mode in
parallel to Quartz and was putting out test releases for adventurous
users.
The test releases were called XFree86-Aqua, or XAqua for short.
Since Torrey had taken the lead, changes went directly to
XFree86's CVS repository, which was heading towards the 4.1.0
release.
</p>
      <p>
In the first stages interfacing with Quartz was done via a small
application called Xmaster.app (written with Carbon, then rewritten
with Cocoa).
Later that code was integrated into the X server proper, giving birth
to XDarwin.app.
Shared library support was also added at this time (and Tenon was
convinced to use this set of patches instead of their own to ensure
binary compatibility).
There was even good progress on a rootless mode (using the Carbon
API), but alas, it was too late to get it into XFree86 4.1.0.
And the rootless patch was free, and continued to float around the
net.
After XFree86 4.1.0 shipped with just the fullscreen mode, work on the
rootless mode continued, now using the Cocoa API.
An experimental rootless mode was put into XFree86's CVS repository.
</p>
      <p>
In the meantime, Apple released Mac OS X 10.0 and Darwin 1.3,
and Tenon released Xtools 1.0 some weeks after that.
</p>
      <p>Development continued on integrating the rootless mode into XFree86,
so that by the time XFree86 4.2.0 shipped in January 2002, the Darwin/Mac OS X 
version had been completely integrated into the main XFree86 distribution.
</p>
    
  <h2><a name="inst-xfree86">3 Getting and Installing X11</a></h2>
    
    
    <h3><a name="inst-xfree86.fink">3.1 Installing X11 via Fink</a></h3>
      
      <p>
Fink will let you install X11 in a variety of ways,
among these it provides XFree86 packages of its own. If you
use <tt style="white-space: nowrap;">fink install ...</tt>, it will download
the source code and compile it on your computer. If
you use <tt style="white-space: nowrap;">apt-get install ...</tt> or the
<tt style="white-space: nowrap;">dselect</tt> frontend, it will download
precompiled binary packages, similar to the official
XFree86 distribution.
</p>
<p><b>General notes:</b></p>
<ul><li>All of the X11 packages currently available via Fink support both full-screen and rootless
operation, and have OpenGL support.</li>
<li><b>Important note:</b>  Files get moved around between X11 releases.  This frequently means that if you try to downgrade your X11 installation, you will find that binaries (executable programs, etc.) won't work anymore.  You'd have to rebuild any such packages.
<p>You can go the other way though:  packages built vs an older X11 generally work on a later one.</p>
<p>For 10.3 or 10.4, the X11 hierarchy (newer -&gt; older codebases) is as follows:</p>
<pre>xorg &gt; xfree86 &gt; Apple's X11 </pre>
</li></ul>
<p><b>10.4 users:</b></p>
<p>You can install XFree86 version 4.5.0-23 from source.   You will need both the <tt style="white-space: nowrap;">xfree86</tt> and <tt style="white-space: nowrap;">xfree86-shlibs</tt> packages to have a fully functional installation.</p>
<p>You can also install the X.org X11 release (currently version 6.8.2-35) via the <tt style="white-space: nowrap;">xorg</tt> and <tt style="white-space: nowrap;">xorg-shlibs</tt> packages in the unstable tree.  This X11 flavor is similar to XFree86-4.5, but includes some bugfixes and new features, and removes some code with a disputed license.</p>
<p><b>10.3 users:</b></p>
<p>You can install XFree86 version 4.4.0-13 (that which is in the current binary distribution) or 4.5.0-13 (which is available from source).  You will need both the <tt style="white-space: nowrap;">xfree86</tt> and <tt style="white-space: nowrap;">xfree86-shlibs</tt> packages to have a fully functional installation.</p>
<p>You can also install X.org-6.8.2 via the <tt style="white-space: nowrap;">xorg</tt> and <tt style="white-space: nowrap;">xorg-shlibs</tt> packages as above.</p>

<p><b>10.2 users:</b></p>
<p>10.2 users may install version 4.3 via source or binary, and 4.4 from the unstable tree.  As above, you'll install <tt style="white-space: nowrap;">xfree86</tt> and <tt style="white-space: nowrap;">xfree86-shlibs</tt>.
</p>

      <p>XFree86 4.2.1.1 is also available for 10.2, in <tt style="white-space: nowrap;">normal</tt> and <tt style="white-space: nowrap;">-threaded</tt> flavors (later X11s all have threading support), though it is considered to be obsolete. The <tt style="white-space: nowrap;">xfree86-base</tt>, <tt style="white-space: nowrap;">xfree86-base-shlibs</tt>, <tt style="white-space: nowrap;">xfree86-shlibs</tt>, and <tt style="white-space: nowrap;">xfree86-rootless-shlibs</tt> packages (or their <tt style="white-space: nowrap;">-threaded</tt> counterparts must all be installed for you to have a working XFree86 setup.  In addition, you may need to install the <tt style="white-space: nowrap;">xfree86-base-dev</tt> and <tt style="white-space: nowrap;">xfree86-rootless-dev</tt> packages (or their <tt style="white-space: nowrap;">-threaded</tt> equivalents) to keep Fink from trying to install a newer version.</p>
      
<p><b>10.1 users:</b></p>
<p>You can install version 4.2.0 from the binary distribution (only).  You will install <tt style="white-space: nowrap;">xfree86-base</tt> and <tt style="white-space: nowrap;">xfree86-rootless</tt>.</p>
    
    <h3><a name="inst-xfree86.apple-binary">3.2 Apple's Binaries</a></h3>
      
      <p>
On January 7, 2003, Apple released <a href="http://www.apple.com/macosx/x11/">a custom
X11 implementation based on XFree86-4.2</a> which includes Quartz rendering and accelerated
OpenGL.  A new version was released on February 10, 2003 with additional features and bugfixes.  A third release (i.e. Beta 3) was made on March 17, 2003 with further additional features and bugfixes.  This version is usable on Jaguar.
</p>
      <p>On October 24, 2003, Apple released Panther (10.3), which includes a release version of their X11 distribution.  This version is based on XFree86-4.3.</p>
<p>On April 29, 2005, Apple released Tiger (10.4), which includes a release version of Apple's X11 based on XFree86-4.4.</p>
      <p>
To use the Apple binaries, you need to make sure the <b>X11 User</b> package is installed, and you should also 
<a href="http://www.finkproject.org/doc/users-guide/upgrade.php">update</a> Fink.</p>
      <p>Under <tt style="white-space: nowrap;">fink-0.16.2</tt>, you will need to install the <b>X11 SDK</b> package, as well.  After you do this, Fink will
create a <tt style="white-space: nowrap;">system-xfree86</tt> virtual package.</p>
      <p>Under <tt style="white-space: nowrap;">fink-0.17.0</tt> and later installing the X11 SDK is only necessary if 
you want to build packages from source.  In this case, even if you don't have the SDK, there will be <tt style="white-space: nowrap;">system-xfree86</tt>
and <tt style="white-space: nowrap;">system-xfree86-shlibs</tt> virtual packages, the latter representing the shared libraries.  If you do install the SDK, there will also be a  
<tt style="white-space: nowrap;">system-xfree86-dev</tt> package, representing the headers.
</p>
      <p>
If you have an existing XFree86 distribution installed, be it through Fink or otherwise, you
can follow the <a href="#inst-xfree86.switching-x11">instructions on
replacing one X11 package with another</a>.  Make sure that you remove your existing
packages, then install Apple's X11 (and X11 SDK, if needed or desired).
</p>
      <p>
Some notes on using Apple's X11:
</p>
      <ul>
        <li>
          <p>The <tt style="white-space: nowrap;">autocutsel</tt> package is no longer needed.  If you're starting
  X11 with it enabled, you should disable it.</p>
        </li>
        <li>
          <p>Apple's X11 uses your existing <tt style="white-space: nowrap;">~/.xinitrc</tt> file.  If you want the
  full effect of Quartz integration, you should use <tt style="white-space: nowrap;">/usr/X11R6/bin/quartz-wm</tt>
  as your window manager, or delete your <tt style="white-space: nowrap;">~/.xinitrc</tt> completely.</p>
          <p>If you just want cut-and-paste integration, but want to use a different window manager, you can do 
this as in the following example:</p>
          <pre>/usr/X11R6/bin/quartz-wm --only-proxy &amp;
exec /sw/bin/fvwm2</pre>
          <p>You may, of course, call any other window manager, <tt style="white-space: nowrap;">startkde</tt>, etc.</p>
        </li>
        <li>
          <p>
            <tt style="white-space: nowrap;">quartz-wm</tt> doesn't fully support Gnome/KDE window manager hints, so
  you may see some strange behavior on windows that shouldn't have decorations, but do.</p>
        </li>
        <li>
          <p>Apple X11 doesn't honor the Fink environment settings by default.  In order to call up startup applications 
that you have installed with fink (e.g. window managers, gnome-session, other apps under 
<tt style="white-space: nowrap;">/sw/bin</tt>) put the following near the top of <tt style="white-space: nowrap;">~/.xinitrc</tt> (i.e. after the 
initial "<tt style="white-space: nowrap;">#!/bin/sh</tt>", but before you run any programs):</p>
          <pre> . /sw/bin/init.sh
</pre>
          <p>so that the Fink environment is initialized.  Note:  <tt style="white-space: nowrap;">init.sh</tt> is used rather than <tt style="white-space: nowrap;">init.csh</tt> because <tt style="white-space: nowrap;">.xinitrc</tt> is run by <tt style="white-space: nowrap;">sh</tt> rather than <tt style="white-space: nowrap;">tcsh</tt>.</p>
        </li>
        <li>
          <p>Applications that require calling other programs which reside within your Fink tree for some of their functions need special treatment to get them to work when called from the Application menu.  Instead of putting just the full path to the filename, e.g.</p>
          <pre>/sw/bin/emacs</pre>
          <p>you'll want to use something like the following, if you're using bash as your
default shell:</p>
          <pre>. /sw/bin/init.sh ; emacs</pre>
          <p>and if you're using tcsh:</p>
          <pre>source /sw/bin/init.csh ; emacs</pre>
          <p>This makes sure that the application has the correct PATH information.  You can use this syntax for any Fink-installed application.</p>
        </li>
        <li>
          <p>If you are trying to build a package by hand against Apple's X11 and you see a failure like:</p>
          <pre>ld: err.o illegal reference to symbol: _XSetIOErrorHandler 
defined in indirectly referenced dynamic library 
/usr/X11R6/lib/libX11.6.dylib</pre>
          <p>then you'll need to make sure to that <tt style="white-space: nowrap;">-lX11</tt> is present during linking.  Check your package's configuration options to see how to feed it the extra argument.</p>
        </li>
        <li>
          <p>If you use the <tt style="white-space: nowrap;">xfree86</tt> package, and later switch to Apple's X11 (on either 10.2.x or 10.3.x), any
packages you have built against <tt style="white-space: nowrap;">xfree86</tt> will need to be rebuilt, as the binaries are incompatible.</p>
        </li>
<li><p><b>10.3 and 10.4 users only:</b>  It is possible to use Apple's display server and window manager on top of XFree86 or X.org.  If you install the <tt style="white-space: nowrap;">applex11tools</tt> package, Fink will install what you need, as long as you have a copy of X11User.pkg.</p></li>
      </ul>
      <p>For more information on using Apple's X11, check out this <a href="http://developer.apple.com/darwin/runningx11.html">article</a> at the Apple Developer Connection.</p>
    
    <h3><a name="inst-xfree86.official-binary">3.3 The Official Binaries</a></h3>
      
      <p>
The XFree86 project has an official binary distribution of XFree86
4.5.0.  You can find it on your local <a href="http://www.xfree86.org/mirrors">XFree86 mirror</a> in
the directory <tt style="white-space: nowrap;">4.5.0/binaries/Darwin-ppc-6.x</tt> (or <tt style="white-space: nowrap;">4.5.0/binaries/Darwin-ppc-5.x</tt> for OS 10.1).  
Be sure to get the <tt style="white-space: nowrap;">Xprog.tgz</tt> and <tt style="white-space: nowrap;">Xquartz.tgz</tt>
tarballs even though they are marked as "optional".
If you're unsure what you need, just download the whole directory.
Run the <tt style="white-space: nowrap;">Xinstall.sh</tt> script as root to install the stuff.
(You might want to read the <a href="http://www.xfree86.org/4.5.0/Install.html">official
instructions</a> before installing.)</p>

      <p>You've now got XFree86 with a server that can do fullscreen, or 
rootless under Mac OS X.
</p>
    
    <h3><a name="inst-xfree86.official-source">3.4 The Official Source</a></h3>
      
      <p>
If you've got the time to spare, you can build XFree86 4.5 from
source.
You can find the source on your local <a href="http://www.xfree86.org/mirrors/">XFree86 mirror</a> in
the directory <tt style="white-space: nowrap;">4.5.0/source</tt>.
Grab all seven <tt style="white-space: nowrap;">XFree86-4.5.0-src-#.tgz</tt> tarballs and extract them in
the same directory.
You can customize the build by putting macro definitions in the file
<tt style="white-space: nowrap;">config/cf/host.def</tt> in the XFree86 source tree.

See
<tt style="white-space: nowrap;">config/cf/darwin.cf</tt> for some hints.
(Note: Only the macros that have an #ifndef check around them can be
overwritten in host.def.)
</p>
      <p>
When you're happy with your configuration, compile and install XFree86
with the following commands:
</p>
      <pre>make World
sudo make install install.man</pre>

      <p>
As with the official binaries, you've now got XFree86 with a server
that can do fullscreen, or rootless under Mac OS X.
</p>
    
    <h3><a name="inst-xfree86.latest-cvs">3.5 The Latest Development Source</a></h3>
      
      <p>
If you have not only time, but also some nerves to spare you can get
the latest development version of XFree86 from the public CVS
repository.
Note that the code is under constant development; what you get today
is usually not the same as what you got yesterday.
</p>
      <p>
To install, follow the <a href="http://www.xfree86.org/cvs/">XFree86
CVS</a> instructions to download the <tt style="white-space: nowrap;">xc</tt> module.
Then, follow the source build instructions above.
</p>
    
    

    <h3><a name="inst-xfree86.switching-x11">3.6 Replacing X11</a></h3>
      
      <p>
If you have already installed one of the Fink X11 packages but for one reason or another
have decided you need to remove one and replace it with another, the procedure is pretty
straightforward.  You will have to force a removal of the old packages, and then install the
new, to keep your dpkg database consistent.
</p>
      <p>
There are two different ways to do this:
</p>
      <ol>
        <li>
          <p>Use FinkCommander</p>
          <p>
   If you are using <a href="http://finkcommander.sourceforge.net/">FinkCommander</a>, you
   can force removal through the menu.  For example, if you have
   <tt style="white-space: nowrap;">xfree86-rootless</tt> installed, but want the threaded version, you
   can select your <tt style="white-space: nowrap;">xfree86-rootless</tt>,
   <tt style="white-space: nowrap;">xfree86-rootless-shlibs</tt>, <tt style="white-space: nowrap;">xfree86-base</tt>, and
   <tt style="white-space: nowrap;">xfree86-base-shlibs</tt> packages, and then run:
  </p>
          <pre>Source -&gt; Force Remove</pre>
        </li>
        <li>
          <p>Manually Remove from the Command-Line</p>
          <p>
   To manually, remove them, you use the <tt style="white-space: nowrap;">dpkg</tt> with the --force-depends
   option, like so:
  </p>
          <pre>sudo dpkg -r --force-depends xfree86-rootless\ 
xfree86-rootless-shlibs xfree86-base xfree86-base-shlibs</pre>
          <p>
   Note that if you have apps that require threaded XFree86, you may have trouble with your
   dpkg database if you force remove it and install a different XFree86 package or placeholder
   package.
  </p>
        </li>
      </ol>
      <p>If, on the other hand, you have an X11 version that was not installed via Fink, you'll need to remove it via the command line:</p>
      <pre>sudo rm -rf /usr/X11R6 /etc/X11</pre>
      <p>The above holds true for removing any flavor of X11 that you didn't install through Fink.  You will also need to remove <tt style="white-space: nowrap;">XDarwin.app</tt> | 
<tt style="white-space: nowrap;">X11.app</tt>, depending on what you had installed.  Make sure to check your <tt style="white-space: nowrap;">.xinitrc</tt> if you are removing Apple's X11 to 
make sure that you aren't trying to run <tt style="white-space: nowrap;">quartz-wm</tt>.  You can now install whatever new X11 variety you want, manually or via Fink.</p>
    
    <h3><a name="inst-xfree86.fink-summary">3.7 Fink package summary</a></h3>
      
      <p>
A quick summary of the install options and the Fink packages you
should install:
</p>
      <table border="0" cellpadding="0" cellspacing="10"><tr valign="bottom"><th align="left">Install Type</th><th align="left">Fink packages</th></tr><tr valign="top"><td>XFree86-4.4.0 or 4.5.0 (10.3 and 10.4)</td><td>
            <p>
              <tt style="white-space: nowrap;">xfree86</tt> and <tt style="white-space: nowrap;">xfree86-shlibs</tt>
            </p>
          </td></tr><tr valign="top"><td>X.org-6.8.2 (10.3 and 10.4)</td><td>
	    <p><tt style="white-space: nowrap;">xorg</tt> and <tt style="white-space: nowrap;">xorg-shlibs</tt></p>
	</td></tr><tr valign="top"><td>Apple's X11 (all versions)</td><td>
            <p>
              <tt style="white-space: nowrap;">system-xfree86</tt> and <tt style="white-space: nowrap;">system-xfree86-shlibs</tt> (+<tt style="white-space: nowrap;">system-xfree86-dev</tt> for building X11-based packages)</p>
          </td></tr><tr valign="top"><td>XFree86-4.x official binaries</td><td>
            <p>
	      <tt style="white-space: nowrap;">system-xfree86</tt> and <tt style="white-space: nowrap;">system-xfree86-shlibs</tt> (+<tt style="white-space: nowrap;">system-xfree86-dev</tt> for building X11-based packages)
            </p>  
          </td></tr><tr valign="top"><td>XFree86-4.x built from source, or from the latest CVS source</td><td>
            <p>
	      <tt style="white-space: nowrap;">system-xfree86</tt> and <tt style="white-space: nowrap;">system-xfree86-shlibs</tt> (+<tt style="white-space: nowrap;">system-xfree86-dev</tt> for building X11-based packages)
              </p>
          </td></tr><tr valign="top"><td>XFree86-4.2.1.x (10.2 only) or 4.2.0 (10.1 only)</td><td>
             <p><tt style="white-space: nowrap;">xfree86-base</tt> and <tt style="white-space: nowrap;">xfree86-rootless</tt> (and their <tt style="white-space: nowrap;">-shlibs</tt>)</p>
            <p>or <tt style="white-space: nowrap;">xfree86-base-threaded</tt> and <tt style="white-space: nowrap;">xfree86-rootless-threaded</tt> (and <tt style="white-space: nowrap;">-shlibs</tt>)</p>
          </td></tr></table>
    
  <h2><a name="run-xfree86">4 Starting X11</a></h2>
    
    
    <h3><a name="run-xfree86.darwin">4.1 Darwin</a></h3>
      
      <p>
On pure Darwin, XFree86 behaves like on any other Unix.
The usual way to start it is via <tt style="white-space: nowrap;">startx</tt> from the console;
that starts both the server and some initial clients like the window
manager and a terminal emulator with a shell.
On pure Darwin it is not necessary to specify any parameters, so you
can just type:
</p>
      <pre>startx</pre>
      <p>
You can customize what is started through several files in your home
directory.
<tt style="white-space: nowrap;">.xinitrc</tt> controls what clients get started.
<tt style="white-space: nowrap;">.xserverrc</tt> controls server options and may even
start a different server.
If you're having trouble (as in, you only get a blank screen or
XFree86 drops you right back to the console), you can start
troubleshooting by moving these files out of the way.
When <tt style="white-space: nowrap;">startx</tt> doesn't find these files, it will use safe
defaults that should always work.
</p>
      <p>
Alternatively, you can start the server directly with one of the XDMCP
options, like this:
</p>
      <pre>X -query remotehost</pre>
      <p>
Details about this can be found in the <tt style="white-space: nowrap;">Xserver</tt> manual
page.
</p>
      <p>
Finally, there is the option to set up <tt style="white-space: nowrap;">xdm</tt>; read its
manual page for details.
</p>
      <p>
Note: If you're running Mac OS X anterior to Panther, you can type <tt style="white-space: nowrap;">&gt;console</tt>
at the login window and you'll get a text console that is
equivalent to pure Darwin.
In case you don't see a field to enter a user's name in the login window, just type the first letter of whichever user's name, following by option-return.
You can use all of the start methods outlined above, with the
exception of <tt style="white-space: nowrap;">xdm</tt>.
</p>
      <p>
Note: If you are running Mac OS X Panther or later, you cannot start XFree86 from the console window.
</p>
    
    <h3><a name="run-xfree86.macosx-41">4.2 Mac OS X + XFree86 4.x.y</a></h3>
      
       <p>
There are basically two ways to start XFree86 under Mac OS X.
One is double-clicking the <tt style="white-space: nowrap;">XDarwin.app</tt> application in your
<tt style="white-space: nowrap;">Applications</tt> folder.  This will let you choose between full 
screen and rootless mode in a dialog at startup. You can disable 
the dialog and set XDarwin always to use the mode of your 
choice in the Preferences dialog.  
</p>
      <p>
Prior to 4.2.0 it would fire up fullscreen mode automatically, 
and there was no way to get rootless mode by double-clicking 
the application.
</p>
      <p>
The other way to start XFree86 under Mac OS X is via
<tt style="white-space: nowrap;">startx</tt> from <tt style="white-space: nowrap;">Terminal.app</tt>.
If you start the server this way, you must tell it that it should run
in parallel with Quartz.
You do this by passing the <tt style="white-space: nowrap;">-fullscreen</tt> option, like this:
</p>
      <pre>startx -- -fullscreen</pre>
      <p>
That will start up the server in fullscreen mode, 
plus the clients in your <tt style="white-space: nowrap;">.xinitrc</tt>.  
</p>
      <p>
NOTE: prior to 4.2, <tt style="white-space: nowrap;">-quartz</tt> was used for fullscreen mode.
</p>
      <p>

You can start it in rootless mode with the 
<tt style="white-space: nowrap;">-rootless</tt> option:</p>
      <pre>startx -- -rootless</pre>
      <p>
The <tt style="white-space: nowrap;">-quartz</tt> option no longer selects fullscreen mode,
but rather uses the default mode set in the preferences.
</p>
      <p>As of version 4.3, if you use <tt style="white-space: nowrap;">startx</tt> without arguments, the startup dialog box will come up.</p>
    
    <h3><a name="run-xfree86.starting-xorg">4.3 Starting X.org</a></h3>
      
     <p>X.org works identically to XFree86 in all respects.</p>
    
    <h3><a name="run-xfree86.starting-apples-x11">4.4 Starting Apple's X11</a></h3>
      
       <p>
	Functionally, Apple's X11 works similarly to XFree86 (e.g. using a <tt style="white-space: nowrap;">.xinitrc</tt> file to control the clients that are launched on startup).  The normal way to run it is by double-clicking the <tt style="white-space: nowrap;">X11.app</tt> icon (whose default location is <tt style="white-space: nowrap;">/Applications/Utilities</tt>).  You can use <tt style="white-space: nowrap;">startx</tt>, as well, but it doesn't have a commmand-line option to set the display mode; <tt style="white-space: nowrap;">X11.app</tt> will start up in whatever mode was previously set in its Preferences.</p>
<p>If you don't set up a different window manager you will be running Apple's <tt style="white-space: nowrap;">quartz-wm</tt> window manager.  <b>X11.app</b>'s Preferences give the option to switch between fullscreen and rootless modes without restarting.  However, this doesn't work for quartz-wm; it is necessary to choose a different window manager (e.g. in <tt style="white-space: nowrap;">.xinitrc</tt>)</p>
    
    <h3><a name="run-xfree86.applex11tools">4.5 The applex11tools package</a></h3>
      
      <p>Fink's <tt style="white-space: nowrap;">applex11tools</tt> package allows the use of <tt style="white-space: nowrap;">X11.app</tt> and <tt style="white-space: nowrap;">quartz-wm</tt> under OS 10.3 and later with XFree86 4.4 or later or X.org.</p>
      <p>To install this package you must enable the <a href="http://www.finkproject.org/faq/usage-fink.php#unstable">unstable tree</a>, and have <tt style="white-space: nowrap;">X11User.pkg</tt> somewhere within <tt style="white-space: nowrap;">/Users</tt> or <tt style="white-space: nowrap;">/Volumes</tt>.  <tt style="white-space: nowrap;">X11.app</tt> will be installed in the <tt style="white-space: nowrap;">Applications</tt> folder within your Fink tree.  You can now use either <tt style="white-space: nowrap;">X11.app</tt>  or <tt style="white-space: nowrap;">XDarwin.app</tt>.</p>

    <h3><a name="run-xfree86.xinitrc">4.6 The .xinitrc File</a></h3>
      
      <p>
If a file named <tt style="white-space: nowrap;">.xinitrc</tt> exists in your home
directory, it will be used to start some initial X clients, e.g. the
window manager and some xterms or a desktop environment like GNOME.
The <tt style="white-space: nowrap;">.xinitrc</tt> file is a shell script that contains
the commands to do this.
It is <b>not</b> necessary to put the usual <tt style="white-space: nowrap;">#!/bin/sh</tt>
in the first line and to set the executable bit on the file;
xinit will still know how to run it through a shell.
</p>
      <p>
When there is no <tt style="white-space: nowrap;">.xinitrc</tt> file in your home
directory, X11 will use its default file,
<tt style="white-space: nowrap;">/private/etc/X11/xinit/xinitrc</tt>.
You can use the default file as a starting point for your own
.xinitrc:
</p>
      <pre>cp /private/etc/X11/xinit/xinitrc ~/.xinitrc</pre>
      <p>
If you're using Fink, you should source <tt style="white-space: nowrap;">init.sh</tt> right at the beginning to make sure the environment is set up correctly.
</p>
      <p>
You can put fairly arbitrary commands in an <tt style="white-space: nowrap;">.xinitrc</tt>,
but there are some caveats.
First, the shell that interprets the file will by default wait for
every program to finish before it starts the next one.
If you want several programs to run in parallel, you must tell the
shell to put them "in the background" by adding a <tt style="white-space: nowrap;">&amp;</tt> at
the end of the line.
</p>
      <p>
Second, <tt style="white-space: nowrap;">xinit</tt> waits for the <tt style="white-space: nowrap;">.xinitrc</tt>
script to finish and interprets that as "the session has ended, I should
kill the X server now, too".
This means that the last command of your <tt style="white-space: nowrap;">.xinitrc</tt>
must not be run in the background and it should be a long-living program.
Customarily, the window manager is used for this purpose.
In fact, most window managers assume that <tt style="white-space: nowrap;">xinit</tt> is
waiting for them to finish and use this to make the "Log out" entry in
their menus work.
(Note: To save some memory and CPU cycles, you can put an
<tt style="white-space: nowrap;">exec</tt> before the last line like in the examples below.)
</p>
      <p>
A simple example that starts up GNOME on XFree86 or Xorg:
</p>
      <pre>. /sw/bin/init.sh
exec gnome-session</pre>
      <p>A more complex example for bash users that turns the X11 bell off, starts some clients and finally executes the Enlightenment window manager:</p>
      <pre>. /sw/bin/init.sh

xset b off

xclock -geometry -0+0 &amp;
xterm &amp;
xterm &amp;

exec enlightenment</pre>
 
      <p>To start GNOME 2.4 and later under Apple's X11:</p>
      <pre>. /sw/bin/init.sh
quartz-wm --only-proxy &amp;
exec gnome-session
</pre>
      <p>To start KDE 3.2 (version &lt; 3.2.2-21) under Apple's X11</p>
      <pre>. /sw/bin/init.sh
export KDEWM=kwin
quartz-wm --only-proxy &amp;
/sw/bin/startkde &gt;/tmp/kde.log 2&gt;&amp;1
</pre>
      <p>And finally to start the latest unstable version of KDE under Apple's X11:</p>
      <pre>. /sw/bin/init.sh
/sw/bin/startkde &gt;/tmp/kde.log 2&gt;&amp;1
</pre>
    
    <h3><a name="run-xfree86.oroborosx">4.7 OroborOSX</a></h3>
    
    <p><a href="http://oroborosx.sourceforge.net">OroborOSX</a> is an alternative to the X11.app and XDarwin display servers.  It requires a preexisting X11 installation to work.  <tt style="white-space: nowrap;">X11.app</tt> or <tt style="white-space: nowrap;">XDarwin.app</tt> continue to function, as well</p>
    <p>When run, <b>OroborOSX</b> starts its own rootless-only window manager, and doesn't read in either the system's <tt style="white-space: nowrap;">xinitrc</tt> or user's <tt style="white-space: nowrap;">.xinitrc</tt> files.  After starting, it does have a menu option to execute <tt style="white-space: nowrap;">.xinitrc</tt>.  However, it does have its own method to set up applications to run when it starts.
It also provides a mechanism to start X11 applications from the Finder via startup scripts.</p>  
<p>For more information visit the <a href="http://oroborosx.sourceforge.net">OroborOSX homepage</a>.</p>
      
<h2><a name="xtools">5 Xtools</a></h2>
    
    
    <h3><a name="xtools.install">5.1 Installing Xtools</a></h3>
      
      <p>
Now that's easy for a change.
Get the installer, double-click it, and follow the instructions.
Be sure to select the startup volume when asked.
</p>
      <p>
If you're using Fink, you should install the
<tt style="white-space: nowrap;">system-xtools</tt> package after you've installed Xtools.
That package will not install any files, it will just check that the
libraries etc. are there and act as a placeholder in Fink's dependency
system.
</p>
    
    <h3><a name="xtools.run">5.2 Running Xtools</a></h3>
      
      <p>
To run Xtools, double-click Xtools.app in your Applications folder.
Like XFree86, Xtools will run the clients you specify in your
<tt style="white-space: nowrap;">.xinitrc</tt> file.
Xtools additionally allows you to start clients via the menu.
</p>
    
    <h3><a name="xtools.opengl">5.3 OpenGL Notes</a></h3>
      
      <p>
Xtools does hardware-accelerated OpenGL in rootless mode and comes
with the libraries to support it.
While the main libGL library is fine, the libGLU and libglut libraries
are only present as static libraries, which is not sufficient for
full binary compatibility with XFree86.
Also, some headers are missing.
Fink doesn't offer a workaround at this time.
Hopefully this will be fixed in Xtools 1.1 once it is released.
</p>
    
  <h2><a name="other">6 Other X11 Possibilities</a></h2>
    
    
    <h3><a name="other.vnc">6.1 VNC</a></h3>
      
      <p>
VNC is a network-capable graphics display system similar in design to
X11.
However, it works at a lower level, making implementation easier.
With the Xvnc server and a Mac OS X display client, it is possible to
run X11 applications with Mac OS X.
Jeff Whitaker's <a href="http://www.cdc.noaa.gov/~jsw/macosx_xvnc/">Xvnc page</a> has
more information on that.
</p>
    
    <h3><a name="other.wiredx">6.2 WiredX</a></h3>
      
      <p>
        <a href="http://www.jcraft.com/wiredx/">WiredX</a> is an X11
server written in Java.
It also supports rootless mode.
An Installer.app package is available at the web site.
</p>
    
    <h3><a name="other.exodus">6.3 eXodus</a></h3>
      
      <p>
According to the website, <a href="http://www.powerlan-usa.com/exodus/">eXodus 8</a> by Powerlan
USA runs natively on Mac OS X.
It is unknown what codebase it uses and whether/how it supports local
clients.
Because of this, there is no special support for eXodus in Fink.
If you have more info, please throw it our way.
</p>
    
  <h2><a name="trouble">7 Troubleshooting XFree86</a></h2>
    
    
    <h3><a name="trouble.immedate-quit">7.1 When I launch XDarwin, it quits
or crashes almost immediately</a></h3>
      
      <p>
First of all: Don't Panic!
There are lots of things than can go wrong with XFree86, and a good
number of them can cause startup failures.
Further, it is not unusual that XDarwin crashes when it experiences
startup problems.
This section tries to provide a comprehensive list of problems you may
come across.
But first, you need to gather two important pieces of information:
</p>
      <p>
        <b>XDarwin version.</b>
You can find the XDarwin version in the Finder by clicking
<b>once</b> on the XDarwin icon and then selecting "Show Info"
from the menu.
The version is only incremented when a new binary test release is made
by the XonX project, so "1.0a1" may actually be any version between
1.0a1 and 1.0a2.
</p>
      <p>
        <b>Error messages.</b>
These are essential in pinpointing the particular problem you
experience.
How you get the error messages depends on how you started XDarwin.
If you ran <tt style="white-space: nowrap;">startx</tt> from a Terminal window, you'll have the
messages right there in that window.
Remember that you can scroll up.
If you started XDarwin by double-clicking the icon, the messages end
up in the system log, which you can access through the Console
application in the Utilities folder.
Be sure to pick the right set of messages, i.e. the last one.
</p>
      <p>
We'll start with a list of the messages you may see:
</p>
      <pre>_XSERVTransmkdir: Owner of /tmp/.X11-unix should be set to root</pre>
      <pre>_IceTransmkdir: Owner of /tmp/.ICE-unix should be set to root</pre>
      <p>
Class: Harmless.
X11 creates hidden directories in /tmp to store the socket "files" for
local connections.
For security reasons, X11 prefers if these directories are owned by
root, but since they are world-writable anyway it will still run
without any problems.
(Note: It's quite hard to have these dirs owned by root, as Mac OS X
wipes out /tmp on reboots and XDarwin doesn't run with root privileges
and doesn't need to.)
</p>
      <pre>QuartzAudioInit: AddIOProc returned 1852797029</pre>
      <pre>-[NSCFArray objectAtIndex:]: index (2) beyond bounds (2)</pre>
      <pre>kCGErrorIllegalArgument : CGSGetDisplayBounds (display 35434400)</pre>
      <pre>No core keyboard</pre>
      <p>
Class: Bogus.
These are follow-up errors that result when the server tries to reset
itself after a previous error.
During that, another copy of the startup banner is printed, followed
by one or more of the above messages because resetting the server
doesn't really work in the affected versions of XDarwin.
So when you see messages like these, scroll up in the Terminal
resp. Console window and look for another set of banner and messages.
This affects all versions up to and including XDarwin 1.0a3; it was
fixed after 1.0a3 was released.
</p>
      <pre>cat: /Users/chrisp/.Xauthority: No such file or directory</pre>
      <p>
Class: Mostly harmless.
It is unknown where these messages come from and they seem to have no
impact on operations.
You can get rid of them by running <tt style="white-space: nowrap;">touch .Xauthority</tt> in
your home directory.
</p>
      <pre>Gdk-WARNING **: locale not supported by C library</pre>
      <p>
Class: Harmless.
This just means what it says and won't keep the application from
working.
For more information, <a href="#trouble.locale">see below</a>.
</p>
      <pre>Gdk-WARNING **: locale not supported by Xlib, locale set to C
Gdk-WARNING **: can not set locale modifiers</pre>
      <p>
Class: Bad, but not fatal.
These messages may appear in addition to the one above.
This indicates that XFree86's locale data files are not present.
It appears that this happens unreproducibly when building Free86 from
source.
Most applications will still work, GNU Emacs is a notable exception.
</p>
      <pre>Unable to open keymapping file USA.keymapping.
Reverting to kernel keymapping.</pre>
      <p>
Class: Often fatal.
This can happen with XDarwin 1.0a1, with the "Load from file"
keymapping option enabled.
That version needs a full path when the file to load is set via the
Preferences dialog, but searches automatically when it is passed on
the command line.
The message will usually be followed by the "assert" message shown
below.
To fix this, follow the directions below.
</p>
      <pre>Fatal server error:
assert failed on line 454 of darwinKeyboard.c!</pre>
      <pre>Fatal server error:
Could not get kernel keymapping! Load keymapping from file instead.</pre>
      <p>
Class: Fatal.
Changes Apple made in Mac OS X 10.1 broke the code in XFree86 that
reads the keyboard layout from the operating system kernel;
the message above is the result of that.
You must use the "Load from file" keymapping option on Mac OS X 10.1.
The setting is in the XDarwin Preferences dialog.
Be sure that a file is selected (i.e. use the "Pick file" button) -
simply activating the check box may not be sufficient with some
versions of XDarwin.
If you can't get to the Preferences dialog because XDarwin closes
before you get a chance, run it from Terminal with the command
<tt style="white-space: nowrap;">startx -- -quartz -keymap USA.keymapping</tt>.
This usually allows XDarwin to start up, and you can then make the
permanent choice in the Preferences dialog.
</p>
      <pre>Fatal server error:
Could not find keymapping file .</pre>
      <p>Class: Fatal (as it says).  This error is due to the absence of the keymapping files under Panther.  You need to install <tt style="white-space: nowrap;">xfree86-4.3.99-16</tt> or later, since these versions don't need the keymapping files.</p>
      <pre>Warning: no access to tty (Inappropriate ioctl for device).
Thus no job control in this shell.</pre>
      <p>
Class: Mostly harmless.
XDarwin 1.0a2 and later launch an interactive shell behind the scenes
to run your client startup file (.xinitrc).
This was done so that you don't have to add statements to set up PATH
in that file.
Some shells complain that they're not connected to a real terminal,
but that can be ignored since that shell instance is not used for
anything that requires job control or the like.
</p>
      <pre>Fatal server error:
failed to connect as window server!</pre>
      <p>
Class: Fatal.
This means that the console-mode server (for pure Darwin) got started
while you were logged into Aqua.
Usually this happens when you installed the official XFree86 binary
distribution and left out the Xquartz.tgz tarball.
It can also happen when the symlinks in /usr/X11R6/bin are messed up
or when you issue the command <tt style="white-space: nowrap;">XDarwin</tt> in a Terminal
window to start the server (you should use startx instead in that
case, see <a href="#run-xfree86">Starting XFree86</a>).
</p>
      <p>
In any case, you can run <tt style="white-space: nowrap;">ls -l /usr/X11R6/bin/X*</tt> and
check the output.
You should see four relevant entries:
<tt style="white-space: nowrap;">X</tt>, a symlink pointing at <tt style="white-space: nowrap;">XDarwinStartup</tt>;
<tt style="white-space: nowrap;">XDarwin</tt>, an executable file (this is the console
mode server);
<tt style="white-space: nowrap;">XDarwinQuartz</tt>, a symlink pointing at
<tt style="white-space: nowrap;">/Applications/XDarwin.app/Contents/MacOS/XDarwin</tt>;
and <tt style="white-space: nowrap;">XDarwinStartup</tt>, a small executable file.
If any of these are missing or pointing at different files, you need
to fix that.
How you do that depends on the method you used to install XFree86.
If you installed XFree86 with Fink then you need to reinstall the <tt style="white-space: nowrap;">xfree86</tt> package (or <tt style="white-space: nowrap;">xfree86-rootless</tt> for OS 10.2 and earlier).  If you installed it by yourself, then get the files from a copy of Xquartz.tgz.
</p>
      <pre>The XKEYBOARD keymap compiler (xkbcomp) reports:
&gt; Error:            Can't find file "unknown" for geometry include
&gt;                   Exiting
&gt;                   Abandoning geometry file "(null)"
Errors from xkbcomp are not fatal to the X server</pre>
      <p>
Class: Mostly harmless.
As the message says, it is not fatal.
To my knowledge, XDarwin doesn't use the XKB extension at all.
Probably some client program tries to use it anyway...
</p>
      <pre>startx: Command not found.</pre>
      <p>
Class: Fatal.
This can happen with XDarwin 1.0a2 and 1.0a3 when your shell
initialization files are not set up to add /usr/X11R6/bin to the PATH
variable.
If you use Fink and haven't changed your default shell, adding the
line <tt style="white-space: nowrap;">source /sw/bin/init.csh</tt> to <tt style="white-space: nowrap;">.cshrc</tt>
in your home directory (as recommended by the Fink instructions) should
be sufficient.
</p>
      <pre>_XSERVTransSocketUNIXCreateListener: ...SocketCreateListener() failed
_XSERVTransMakeAllCOTSServerListeners: server already running</pre>
      <pre>Fatal server error:
Cannot establish any listening sockets - Make sure an X server isn't already
running</pre>
      <p>
Class: Fatal.
This can happen when you accidentally run several instances of XDarwin
at once,
or maybe after an unclean shutdown (i.e. crash) of XDarwin.
It might also be a file permission problem with the sockets for local
connections.
You can try to clean that up with <tt style="white-space: nowrap;">rm -rf /tmp/.X11-unix</tt>.
Restarting the computer also helps in most cases (Mac OS X
automatically cleans up /tmp when it boots, and the network stack is
reset).
</p>
      <pre>Xlib: connection to ":0.0" refused by server
Xlib: Client is not authorized to connect to Server</pre>
      <p>
Class: Fatal.
The client programs can't connect to the display server (XDarwin)
because they use bogus authentication data.
This can be caused by some VNC installations,
by running XDarwin through sudo,
and probably some other freak accidents.
The usual fix is to delete the .Xauthority file (which stores the
authentication data) in your home directory and re-create an empty
file:
</p>
      <pre>cd
rm .Xauthority
touch .Xauthority</pre>
      
      <p>
Another common cause for XFree86 startup failures is an incorrect
<tt style="white-space: nowrap;">.xinitrc</tt> file.
What happens is that the <tt style="white-space: nowrap;">.xinitrc</tt> is run and for some
reason terminates almost immediately.
<tt style="white-space: nowrap;">xinit</tt> interprets this as "the user's session has ended"
and kills XDarwin.
See the <a href="#run-xfree86.xinitrc">.xinitrc
section</a> for more details.
Remember to set up the PATH and to have one long-lived program that is
not started in the background.
It is a good idea to add <tt style="white-space: nowrap;">exec xterm</tt> as a fallback when
your window manager or similar can't be found.
</p>
      
    
    <h3><a name="trouble.black">7.2 Black icons in the GNOME panel or in the
menu of a GNOME application</a></h3>
      
      <p>
A common problem is that icons or other images are displayed as black
rectangles or black outlines.
Ultimately, this is caused by limitations in the operating system
kernel.
The problem has been reported to Apple, but so far they seem unwilling
to fix it; see the filed <a href="http://www.opensource.apple.com/bugs/X/Kernel/2691632.html">Darwin
bug report</a> for details.
</p>
      <p>
The current situation is that the MIT-SHM extension of the X11
protocol is practically unusable on Darwin and Mac OS X.
There are two ways to turn the protocol extension off: in the server
or in the clients.
The XFree86 servers installed by Fink (i.e. the xfree86-server and
xfree86-rootless packages) have it turned off.
The GIMP and the GNOME panel have been inoculated as well.
If you experience black icons in another application, start that
application with the <tt style="white-space: nowrap;">--no-xshm</tt> command line option.
</p>
    
    <h3><a name="trouble.keyboard">7.3 The keyboard doesn't work in XFree86</a></h3>
      
      <p>
This is a known problem that so far seems to affect only portables
(PowerBook, iBook).
To work around this, the "Load from file" keymapping option was
implemented.
Nowadays it has become the default because the old method (reading the
mapping from the kernel) stopped working with Mac OS X 10.1.
If you haven't enabled the option already, you can do so in the
XDarwin preferences dialog.
Check the "Load from file" checkbox and select the keymapping file to
load.
After restarting XDarwin, your keyboard should mostly work (see
below).
</p>
      <p>
If you're starting XFree86 from the command line, you can pass the
name of the keymapping file to load as an option, as in:
</p>
      <pre>startx -- -quartz -keymap USA.keymapping</pre>
    
    <h3><a name="trouble.delete-key">7.4 The Backspace key doesn't work</a></h3>
      
      <p>
This can happen when you use the "Load keymapping from file" option
described above.
The mapping files describe the backspace key as "Delete", not as
"Backspace".
You can correct that by putting the following line in your .xinitrc
file:
</p>
      <pre>xmodmap -e "keycode 59 = BackSpace"</pre>
      <p>
If I remember correctly, XDarwin 1.0a2 and later have code that
correctly maps the Backspace key automatically.
</p>
    
    <h3><a name="trouble.locale">7.5 "Warning: locale not supported by C library"</a></h3>
      
      <p>
These messages are quite common, but harmless.
It just means what it says - internationalization is not supported
through the standard C library, the program will use the default
English messages, date formats, and so on.
There are several ways to deal with this:
</p>
      <ul>
        <li>
          <p>
Just ignore the messages.
</p>
        </li>
        <li>
          <p>
Get rid of the messages by unsetting the environment variable LANG.
Note that this will also turn internationalization off in programs
that actually support it (via gettext/libintl).
Example for .xinitrc:
</p>
          <pre>unset LANG</pre>
          <p>
Example for .cshrc:
</p>
          <pre>unsetenv LANG</pre>
        </li>
        <li>
          <p>
(10.1 only) Use the <tt style="white-space: nowrap;">libxpg4</tt> Fink package.
It builds a small library that contains working locale functions and
arranges that it is loaded before the system libraries (using the
DYLD_INSERT_LIBRARIES environment variable).
You may have to set the LANG environment variable to a fully qualified
value, e.g. <tt style="white-space: nowrap;">de_DE.ISO_8859-1</tt> instead of <tt style="white-space: nowrap;">de</tt>
or <tt style="white-space: nowrap;">de_DE</tt>.
</p>
        </li>
        <li>
          <p>
Ask Apple to include proper locale support in a future version of Mac
OS X.
</p>
        </li>
      </ul>
    
  <h2><a name="tips">8 Usage Tips</a></h2>
    
    
    <h3><a name="tips.terminal-app">8.1 Launching X11 apps from Terminal.app</a></h3>
      
      <p>
To launch X11 applications from a Terminal.app window, you must set
the environment variable "DISPLAY".
This variable tells the applications where to find the X11 window
server.
In the default setup - XDarwin runs on the same machine -, you can set the variable as follows:
</p>
      <ul>
        <li><p>For tcsh users:</p>
      <pre>setenv DISPLAY :0.0</pre>
</li>
        <li><p>For bash users:</p>
<pre>export DISPLAY=":0.0"</pre>
</li>
      </ul>
      <p>
A nice setup is to have XDarwin.app started when you log in (settable
in the Login panel of the System Preferences on Mac OS 10.2, in the Accounts panel, Startup items on Mac OS 10.3):
</p>
      <ul>
        <li><p>For tcsh users, add the following to your .cshrc file:</p>
      <pre>if (! $?DISPLAY) then
  setenv DISPLAY :0.0
endif</pre>
</li>
        <li><p>For bash users, add the following to your .bashrc file:</p>
<pre>[[ -z $DISPLAY ]] &amp;&amp; export DISPLAY=":0.0"</pre>
</li>
      </ul>
      <p>
This sets DISPLAY automatically in every shell.
It doesn't override the current value when DISPLAY is already set,
though.
This way you can still run X11 applications remotely or through ssh
with X11 tunneling.
</p>
    
    <h3><a name="tips.open">8.2 Launching Aqua apps from an xterm</a></h3>
      
      <p>
One way to launch Aqua applications from an xterm (or any other shell,
actually) is the <tt style="white-space: nowrap;">open</tt> command.
Some examples:
</p>
      <pre>open /Applications/TextEdit.app
open SomeDocument.rtf
open -a /Applications/TextEdit.app index.html</pre>
      <p>
The second example opens the document in the application that is
associated with it, the third example explicitly gives an application
to use.
</p>
    
    <h3><a name="tips.copy-n-paste">8.3 Copy and Paste</a></h3>
      
      <p>
Copy and Paste generally works between the Aqua and X11 environments.
There are still some bugs.
Emacs is reported to be picky about the current selection.
Copy and paste from Classic to X11 doesn't work.
</p>
      <p>
Anyway, the trick is to use the respective methods of the environment
you're in.
To transfer text from Aqua to X11, use Cmd-C in Aqua, then bring the
destination window to the front and use the "middle mouse button", i.e. Option-click
on a single-button mouse (this can be configured 
under XDarwin's Preferences), to paste.
To transfer text from X11 to Aqua, simply select the text with the
mouse in X11, then use Cmd-V in Aqua to paste it.
</p>
      <p>
The X11 system actually has several separate clipboards (called "cut
buffers" in X11 speak), and some applications have weird views which
one should be used.
In particular, pasting into GNU Emacs or XEmacs sometimes doesn't work
because of this.
The program <tt style="white-space: nowrap;">autocutsel</tt> can help here; it automatically
synchronizes the two main cut buffers.
To run it, install the autocutsel Fink package and add the following
line to your .xinitrc:
</p>
      <pre>autocutsel &amp;</pre>
      <p>
(Make sure it's <b>before</b> the line that exec's the window
manager and never returns! Don't just add it at the end, it won't
be executed.) And remember that it is no more necessary for Apple's X11 (see <a href="#inst-xfree86.apple-binary">Some notes on using Apple's X11</a>).
</p>
      <p>If you are using Apple's X11, then you can use Command-C or Edit-&gt;Copy, as usual for Mac apps, to copy text to the clipboard, and the middle-mouse button or Command-V to paste from the clipboard to Apple X11.</p>
      <p>In any case, if you encounter problems copying or pasting from Aqua to X11 and vice-versa, you may first try to do the pasting part twice (it may happen that the copy does not occur at once), then use intermediate applications, e.g. TextEdit or Terminal.app on the Aqua side, nedit or an xterm on the X11 side. In my experience, there is always a solution.</p>
    
  <hr><h2>Copyright Notice</h2><p>Copyright (c) 2001 Christoph Pfisterer,
Copyright (c) 2001-2011 The Fink Project.
You may distribute this document in print for private purposes,
provided the document and this copyright notice remain complete and
unmodified. Any commercial reproduction and any online publication
requires the explicit consent of the author.</p><hr>
<p>Generated from <i>$Fink: x11.en.xml,v 1.22 2007/08/15 21:57:04 dmacks Exp $</i></p></body></html>
